CADODB

Microsoft ActiveX Data Objects (ADO) enable your client applications to access and manipulate data from a variety of sources through an OLE DB provider. Its primary benefits are ease of use, high speed, low memory overhead, and a small disk footprint. ADO supports key features for building client/server and Web-based applications.

CADODB are a collection of classes to allow to work with ADO using the FreeBasic compilers.

The CADOBase object, from which the other ADO classes inherit, initializes and uninitializes the COM library and implements two methods, GetLastResult and SetResult used by the derived classes to store the result codes of ADO calls.

Folder: Afx/CADODB
Files: CADODB.inc, CADOCommand.inc, CADOConnection.inc, CADOErrors.inc, CADOFields.inc, CADOParameters.inc, CADOProperties.inc, CADORecord.inc, CADORecordset.inc, CADOStream.inc.

CADOBase Class

The CAdoBase class, from which the other ADO classes inherit, initializes and uninitializes the COM library and implements two methods, GetLastResult and SetResult used by the derived classes to store the result codes of ADO calls.

GetLastResult

Returns the last result code.

FUNCTION GetLastResult () AS HRESULT

SetResult

Sets the last result code.

FUNCTION SetResult (BYVAL Result AS HRESULT) AS HRESULT

Return value

The result code returned by the last executed method.

ADO Object Model

ADO objects and their collections:

Connection
  |_ Errors     - Error
  |_ Properties - Property

Command
  |_ Parameters - Parameter
  |_ Properties - Property

Recordset
  |_ Fields - Field
  |_ Properties - Property

Record
  |_ Fields - Field

Stream

ADO Identifiers

' ========================================================================================
' ProgIDs (Program identifiers)
' ========================================================================================

' CLSID = {00000507-0000-0010-8000-00AA006D2EA4}
CONST AFX_PROGID_Command60 = "ADODB.Command.6.0"
' CLSID = {00000514-0000-0010-8000-00AA006D2EA4}
CONST AFX_PROGID_Connection60 = "ADODB.Connection.6.0"
' CLSID = {0000050B-0000-0010-8000-00AA006D2EA4}
CONST AFX_PROGID_Parameter60 = "ADODB.Parameter.6.0"
' CLSID = {00000560-0000-0010-8000-00AA006D2EA4}
CONST AFX_PROGID_Record60 = "ADODB.Record.6.0"
' CLSID = {00000535-0000-0010-8000-00AA006D2EA4}
CONST AFX_PROGID_Recordset60 = "ADODB.Recordset.6.0"
' CLSID = {00000566-0000-0010-8000-00AA006D2EA4}
CONST AFX_PROGID_Stream60 = "ADODB.Stream.6.0"

' ========================================================================================
' Version independent ProgIDs
' ========================================================================================

' CLSID = {00000507-0000-0010-8000-00AA006D2EA4}
CONST AFX_PROGID_Command = "ADODB.Command"
' CLSID = {00000514-0000-0010-8000-00AA006D2EA4}
CONST AFX_PROGID_Connection = "ADODB.Connection"
' CLSID = {0000050B-0000-0010-8000-00AA006D2EA4}
CONST AFX_PROGID_Parameter = "ADODB.Parameter"
' CLSID = {00000560-0000-0010-8000-00AA006D2EA4}
CONST AFX_PROGID_Record = "ADODB.Record"
' CLSID = {00000535-0000-0010-8000-00AA006D2EA4}
CONST AFX_PROGID_Recordset = "ADODB.Recordset"
' CLSID = {00000566-0000-0010-8000-00AA006D2EA4}
CONST AFX_PROGID_Stream = "ADODB.Stream"

' ========================================================================================
' ClsIDs (Class identifiers)
' ========================================================================================

CONST AFX_CLSID_Command = "{00000507-0000-0010-8000-00AA006D2EA4}"
CONST AFX_CLSID_Connection = "{00000514-0000-0010-8000-00AA006D2EA4}"
CONST AFX_CLSID_Parameter = "{0000050B-0000-0010-8000-00AA006D2EA4}"
CONST AFX_CLSID_Record = "{00000560-0000-0010-8000-00AA006D2EA4}"
CONST AFX_CLSID_Recordset = "{00000535-0000-0010-8000-00AA006D2EA4}"
CONST AFX_CLSID_Stream = "{00000566-0000-0010-8000-00AA006D2EA4}"

' ========================================================================================
' IIDs (Interface identifiers)
' ========================================================================================

CONST AFX_IID_ADO = "{00000534-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_Collection = "{00000512-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_Command = "{986761E8-7269-4890-AA65-AD7C03697A6D}"
CONST AFX_IID_Connection = "{00001550-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_DynaCollection = "{00000513-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_Parameter = "{0000150C-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_Record = "{00001562-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_Recordset = "{00001556-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_Stream = "{00001565-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_ADOCommandConstruction = "{00000517-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_ADOConnectionConstruction = "{00000551-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_ADORecordConstruction = "{00000567-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_ADORecordsetConstruction = "{00000283-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_ADOStreamConstruction = "{00000568-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_ConnectionEvents = "{00001400-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_ConnectionEventsVt = "{00001402-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_Error = "{00000500-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_Errors = "{00000501-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_Field = "{00001569-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_Fields = "{00001564-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_Fields_Deprecated = "{00000564-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_Parameters = "{0000150D-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_Properties = "{00000504-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_Property = "{00000503-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_RecordsetEvents = "{00001266-0000-0010-8000-00AA006D2EA4}"
CONST AFX_IID_RecordsetEventsVt = "{00001403-0000-0010-8000-00AA006D2EA4}"

ADO Errors

Any operation involving ADO objects can generate one or more provider errors. As each error occurs, one or more Error objects can be placed in the Errors collection of the Connection object. When another ADO operation generates an error, the Errors collection is cleared, and the new set of Error objects can be placed in the Errors collection.

Each Error object represents a specific provider error, not an ADO error. ADO operations that don't generate an error have no effect on the Errors collection. Use the Clear method to manually clear the Errors collection.

The set of Error objects in the Errors collection describes all errors that occurred in response to a single statement. Enumerating the specific errors in the Errors collection enables your error-handling routines to more precisely determine the cause and origin of an error, and take appropriate steps to recover.

Some properties and methods return warnings that appear as Error objects in the Errors collection but do not halt a program's execution. Before you call the Resync, UpdateBatch, or CancelBatch methods on a Recordset object, the Open method on a Connection object, or set the Filter property on a Recordset object, call the Clear method on the Errors collection. That way you can read the Count property of the Errors collection to test for returned warnings.

The Error object contains details about data access errors that pertain to a single operation involving the provider. Any operation involving ADO objects can generate one or more provider errors. As each error occurs, one or more Error objects are placed in the Errors collection of the Connection object. When another ADO operation generates an error, the Errors collection is cleared, and the new set of Error objects is placed in the Errors collection.

Note: Each Error object represents a specific provider error, not an ADO error. ADO errors are exposed to the run-time exception-handling mechanism. For example, in Microsoft Visual Basic, the occurrence of an ADO-specific error will trigger an On Error event and appear in the Error object. For a complete list of ADO errors, see the ErrorValueEnum table below.

You can read an Error object's properties to obtain specific details about each error, including the following:

• The Description property, which contains the text of the error. This is the default property.
• The Number property, which contains the Long integer value of the error constant.
• The Source property, which identifies the object that raised the error. This is particularly useful when you have several Error objects in the Errors collection following a request to a data source.
• The SQLState and NativeError properties, which provide information from SQL data sources.

When a provider error occurs, it is placed in the Errors collection of the Connection object. ADO supports the return of multiple errors by a single ADO operation to allow for error information specific to the provider. To obtain this rich error information in an error handler, use the appropriate error-trapping features of the language or environment you are working with, then use nested loops to enumerate the properties of each Error object in the Errors collection.

To retrieve information about ADO errors, call the following function:

FUNCTION AfxAdoGetErrorInfo (BYVAL pConnection AS AFX_ADOConnection PTR, BYVAL nError AS HRESULT = 0) AS CBSTR

Where pConnection is a reference to the ADO Connection object and nError the ADO HRESULT code.

ErrorValueEnum Enumeration

Specifies the type of ADO run-time error.

Three forms of the error number are listed:

• Positive decimal—the low two bytes of the full number in decimal format.
• Negative decimal—The decimal translation of the full error number.
• Hexadecimal—The hexadecimal representation of the full error number. The Windows facility code is in the fourth digit. The facility code for ADO error numbers is A. For example: &H800A0E7B.

Note: OLE DB errors may be passed to your ADO application. Typically, these can be identified by a Windows facility code of 4. For example, &H8004....

ADO Properties

Represents a dynamic characteristic of an ADO object that is defined by the provider.

ADO objects have two types of properties: built-in and dynamic.

Built-in properties are those properties implemented in ADO and immediately available to any new object, using the MyObject.Property syntax. They do not appear as Property objects in an object's Properties collection, so although you can change their values, you cannot modify their characteristics.

Dynamic properties are defined by the underlying data provider, and appear in the Properties collection for the appropriate ADO object. For example, a property specific to the provider may indicate if a Recordset object supports transactions or updating. These additional properties will appear as Property objects in that Recordset object's Properties collection. Dynamic properties can be referenced only through the collection, using the MyObject.Properties(0) or MyObject.Properties("Name") syntax.

You cannot delete either kind of property.

A dynamic Property object has four built-in properties of its own:

• The Name property is a string that identifies the property.
• The Type_ property is an integer that specifies the property data type.
• The Value property is a variant that contains the property setting. Value is the default property for a Property object.
• The Attributes property is a long value that indicates characteristics of the property specific to the provider.

The Properties collection contains all the Property objects for a specific instance of an object.

CADOProperty Class Methods

Include file: CAdoProperties.inc (include CADODB.inc).

Attributes (CADOProperty Class)

For a Property object, the Attributes property is read-only, and its value can be the sum of any one or more PropertyAttributesEnum values.

PROPERTY Attributes () AS LONG
PROPERTY Attributes (BYVAL lAttr AS LONG)

Return value

LONG. One or more ParameterAttributesEnum values.

PropertyAttributesEnum

Remarks

When you set multiple attributes, you can sum the appropriate constants. If you set the property value to a sum including incompatible constants, an error occurs.

Remote Data Service Usage

This property is not available on a client-side Connection object.

Example

#include "Afx/CADODB/CADODB.inc"
using Afx

' // Open the connection
DIM pConnection AS CAdoConnection
pConnection.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=biblio.mdb"

' // Open the recordset
DIM pRecordset AS CAdoRecordset
DIM cbsSource AS CBSTR = "SELECT * FROM Publishers ORDER BY PubID"
DIM hr AS HRESULT = pRecordset.Open(cbsSource, pConnection, adOpenKeyset, adLockOptimistic, adCmdText)

' // Parse the Properties collection
DIM pProperties AS CAdoProperties = pRecordset.Properties
DIM nCount AS LONG = pProperties.Count
FOR i AS LONG = 0 TO nCount - 1
   DIM pProperty AS CAdoProperty = pProperties.Item(i)
   PRINT "Property name: "; pProperty.Name; " - Attributes: "; WSTR(pProperty.Attributes)
NEXT

Name (CADOProperty Class)

Returns the name of a Property.

PROPERTY Name () AS CBSTR

Example

#include "Afx/CADODB/CADODB.inc"
using Afx

' // Open the connection
DIM pConnection AS CAdoConnection
pConnection.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=biblio.mdb"

' // Open the recordset
DIM pRecordset AS CAdoRecordset
DIM cvSource AS CVAR = "SELECT * FROM Publishers ORDER BY PubID"
DIM hr AS HRESULT = pRecordset.Open(cvSource, pConnection, adOpenKeyset, adLockOptimistic, adCmdText)

' // Parse the Properties collection
DIM pProperties AS CAdoProperties = pRecordset.Properties
DIM nCount AS LONG = pProperties.Count
FOR i AS LONG = 0 TO nCount - 1
   DIM pProperty AS CAdoProperty = pProperties.Item(i)
   PRINT "Property name: "; pProperty.Name; " - Attributes: "; WSTR(pProperty.Attributes)
NEXT

Type_ (CADOProperty Class)

Returns a DataTypeEnum value that indicates the operational type or data type of a Property object.

PROPERTY Type_ () AS DataTypeEnum

DataTypeEnum

Example

#include "Afx/CADODB/CADODB.inc"
using Afx

' // Open the connection
DIM pConnection AS CAdoConnection
pConnection.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=biblio.mdb"

' // Open the recordset
DIM pRecordset AS CAdoRecordset
DIM cvSource AS CVAR = "SELECT * FROM Publishers ORDER BY PubID"
DIM hr AS HRESULT = pRecordset.Open(cvSource, pConnection, adOpenKeyset, adLockOptimistic, adCmdText)

' // Parse the Properties collection
DIM pProperties AS CAdoProperties = pRecordset.Properties
DIM nCount AS LONG = pProperties.Count
FOR i AS LONG = 0 TO nCount - 1
   DIM pProperty AS CAdoProperty = pProperties.Item(i)
   PRINT "Property name: "; pProperty.Name; " - Type: "; WSTR(pProperty.Type_)
NEXT

Value (CADOProperty Class)

Sets or returns a Variant value that indicates the value of the object. Default value depends on the Type_ property.

PROPERTY Value () AS CVAR
PROPERTY Value (BYREF cvValue AS CVAR)

Example

#include "Afx/CADODB/CADODB.inc"
using Afx

' // Open the connection
DIM pConnection AS CAdoConnection
pConnection.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=biblio.mdb"

' // Open the recordset
DIM pRecordset AS CAdoRecordset
DIM cvSource AS CVAR = "SELECT * FROM Publishers ORDER BY PubID"
DIM hr AS HRESULT = pRecordset.Open(cvSource, pConnection, adOpenKeyset, adLockOptimistic, adCmdText)

' // Parse the Properties collection
DIM pProperties AS CAdoProperties = pRecordset.Properties
DIM nCount AS LONG = pProperties.Count
FOR i AS LONG = 0 TO nCount - 1
   DIM pProperty AS CAdoProperty = pProperties.Item(i)
   PRINT "Property name: "; pProperty.Name; " - Value: "; WSTR(pProperty.Value)
NEXT

CADOProperties Class Methods

Include file: CAdoProperties.inc (include CADODB.inc).

Count (CADOProperties Class)

Retrieves the number of objects of the Properties collection.

PROPERTY Count () AS LONG

Remarks

Because numbering for members of a collection begins with zero, you should always code loops starting with the zero member and ending with the value of the Count property minus 1.

If the Count property is zero, there are no objects in the collection.

Item (CADOProperties Class)

Indicates a specific member of the Properties collection, by name or ordinal number.

PROPERTY Item (BYREF cvIndex AS CVAR) AS Afx_ADOProperty PTR

Return value

An Afx_ADOProperty object reference.

Remarks

If Item cannot find an object in the collection corresponding to the Index argument, an error occurs.

Refresh (CADOProperties Class)

Refreshes the contents of the Properties collection.

FUNCTION Refresh () AS HRESULT

Return value

S_OK (0) or an HRESULT code.

Remarks

Using the Refresh method on a Properties collection of some objects populates the collection with the dynamic properties that the provider exposes. These properties provide information about functionality specific to the provider, beyond the built-in properties ADO supports.